package com.srmt.feishu.client;

import com.lark.oapi.service.docx.v1.model.*;

/**
 * 文档服务接口
 *
 * 定义了飞书文档相关的所有操作
 *
 * <h3>重构说明（v6.0.0）：</h3>
 * <ul>
 *   <li>所有方法返回具体数据类型，不再返回Resp对象</li>
 *   <li>响应校验统一在服务层处理</li>
 *   <li>失败时统一抛出FeishuApiException</li>
 * </ul>
 *
 * @author SRMT Development Team
 * @since 1.0.0
 * @version 6.0.0 统一响应处理层重构
 */
public interface DocxService {

    /**
     * 创建文档
     *
     * @param req 创建文档请求
     * @return 创建的文档对象
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    Document createDocument(CreateDocumentReq req) throws Exception;

    /**
     * 获取文档
     *
     * @param req 获取文档请求
     * @return 文档对象
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    Document getDocument(GetDocumentReq req) throws Exception;

    /**
     * 获取文档块
     *
     * @param req 获取文档块请求
     * @return 文档块对象
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    Block getDocumentBlock(GetDocumentBlockReq req) throws Exception;

    /**
     * 列出文档块
     *
     * @param req 列出文档块请求
     * @return 文档块数组
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    Block[] listDocumentBlock(ListDocumentBlockReq req) throws Exception;

    /**
     * 列出文档的所有块（自动处理分页）
     *
     * 此方法会自动处理分页逻辑，获取文档的所有块，无需手动管理 pageToken
     *
     * @param documentId 文档ID
     * @return 文档中所有块的列表
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    java.util.List<Block> listAllDocumentBlocks(String documentId) throws Exception;

    /**
     * 更新文档块
     *
     * @param req 更新文档块请求
     * @return 更新后的文档块对象
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    Block patchDocumentBlock(PatchDocumentBlockReq req) throws Exception;

    /**
     * 创建文档块子元素
     *
     * @param req 创建文档块子元素请求
     * @return 创建结果（包含子元素ID和客户端token）
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    CreateDocumentBlockChildrenRespBody createDocumentBlockChildren(CreateDocumentBlockChildrenReq req) throws Exception;

    /**
     * 创建文档块后代元素
     *
     * @param req 创建文档块后代元素请求
     * @return 创建结果（包含块ID等信息）
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    CreateDocumentBlockDescendantRespBody createDocumentBlockDescendant(CreateDocumentBlockDescendantReq req) throws Exception;

    /**
     * 批量更新文档块
     *
     * @param req 批量更新文档块请求
     * @return 批量更新结果
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    BatchUpdateDocumentBlockRespBody batchUpdateDocumentBlock(BatchUpdateDocumentBlockReq req) throws Exception;
}